---
title: Config Reference
sidebar_label: devspace.yaml
---

import FragmentConfigImages from '../fragments/config-images.mdx';
import FragmentConfigDeployments from '../fragments/config-deployments.mdx';
import FragmentConfigDev from '../fragments/config-dev.mdx';
import FragmentConfigDependencies from '../fragments/config-dependencies.mdx';
import FragmentConfigVars from '../fragments/config-vars.mdx';
import FragmentConfigProfiles from '../fragments/config-profiles.mdx';
import FragmentConfigCommands from '../fragments/config-commands.mdx';
import FragmentConfigHooks from '../fragments/config-hooks.mdx';
import WarningBuildToolPriority from '../fragments/warning-build-tool-priority.mdx';

## `version`
```yaml
version: v1beta8                   # string   | Version of the config
```

## `images`

<FragmentConfigImages/>

[Learn more about how to configure image building.](../configuration/images/basics.mdx)

### `images[*].build`
```yaml
build:                              # struct   | Build configuration for an image
  docker: ...                       # struct   | Build image with docker and set options for docker
  kaniko: ...                       # struct   | Build image with kaniko and set options for kaniko
  custom: ...                       # struct   | Build image using a custom build script
  disabled: false                   # bool     | Disable image building (Default: false)
```
:::info
Setting the key `docker`, `kaniko`, `custom` or `disabled` will define the build tool for this image.

- If neither `docker`, `kaniko`, `custom` nor `disabled` is specified, `docker` will be used by default.
- By default, `docker` will use `kaniko` as fallback when DevSpace is unable to reach the Docker host.
:::

<WarningBuildToolPriority/>

### `images[*].build.docker`
```yaml
docker:                             # struct   | Options for building images with Docker
  preferMinikube: true              # bool     | If available, use minikube's in-built docker daemon instaed of local docker daemon (default: true)
  skipPush: false                   # bool     | Skip pushing image to registry, enabled automatically for minikube and docker-desktop (Default: false)
  disableFallback: false            # bool     | Disable using kaniko as fallback when Docker is not installed (Default: false)
  useBuildKit: true                 # bool     | Enable BuildKit for Docker build process (default: false)
  options: ...                      # struct   | Set general build options
```

### `images[*].build.kaniko`
```yaml
kaniko:                             # struct   | Options for building images with kaniko
  cache: true                       # bool     | Use caching for kaniko build process
  snapshotMode: "time"              # string   | Type of snapshotMode for kaniko build process (compresses layers)
  insecure: false                   # bool     | Allow working with an insecure registry by not validating the SSL certificate (Default: false)
  args: []                          # string[] | Array of args for kaniko build command
  image: ""                         # string   | Allows to change the kaniko image or kaniko version / image tag.
  pullSecret: ""                    # string   | Mount this Kubernetes secret instead of creating one to authenticate to the registry (default: "")
  additionalMounts: []              # struct[] | Array of mount configurations for Kubernetes Secrets and ConfigMaps that should be mounted into the kaniko build container
  namespace: ""                     # string   | Kubernetes namespace to run kaniko build pod in (Default: "" = deployment namespace)
  options: ...                      # struct   | Set build general build options
```

### `images[*].build.custom`
```yaml
custom:                             # struct   | Options for building images with a custom build script
  command: "./scripts/builder"      # string   | Command to be executed for building (e.g. path to build script or executable)
  args: []                          # string[] | Array of arguments for the custom build command
  imageFlag: string                 # string   | Name of the flag that DevSpace uses to pass the image name + tag to the build script
  onChange: []                      # string[] | Array of paths (glob format) to check for file changes to see if image needs to be rebuilt
```

### `images[*].build.disabled`
```yaml
build:                              # struct   | Build configuration for an image
  disabled: true                    # bool     | Disable image building (Default: false)
```

### `images[*].build.*.options`
```yaml
options:                            # struct   | Options for building images
  target: ""                        # string   | Target used for multi-stage builds
  network: ""                       # string   | Network mode used for building the image
  buildArgs: {}                     # map[string]string | Key-value map specifying build arguments that will be passed to the build tool (e.g. docker)
```


## `deployments`

<FragmentConfigDeployments/>

:::info
Using the `helm` or `kubectl` key will define the type of deployment and the deployment tool to be used.
:::

:::warning
You **cannot** use `helm` and `kubectl` in combination.
:::

### `deployments[*].helm`
```yaml
helm:                               # struct   | Options for deploying with Helm
  chart: ...                        # struct   | Relative path 
  componentChart: false             # bool     | Use the DevSpace component chart instead of a custom `chart` = deployment is a component (Default: false)
  values: {}                        # struct   | Any object with Helm values to override values.yaml during deployment
  valuesFiles:                      # string[] | Array of paths to values files
  - ./chart/my-values.yaml          # string   | Path to a file to override values.yaml with
  replaceImageTags: true            # bool     | Enable automated tag replacement (Default: true)
  wait: false                       # bool     | Wait for pods to start after deployment (Default: false)
  timeout: 180                      # int      | Timeout to wait for pods to start after deployment (Default: 180)
  force: false                      # bool     | Force deleting and re-creating Kubernetes resources during deployment (Default: false)
  atomic: false                     # bool     | Rollback deployment if it fails (Default: false)
  cleanupOnFail: false              # bool     | Delete resources if rollback fails (Default: false)
  recreate: false                   # bool     | Recreate pods for applicable resources, e.g. deployments (Default: false)
  disableHooks: false               # bool     | Disable hooks (Default: false)
  driver: secrets|configmaps|memory # enum     | Driver used by Helm v3 to store release configuration (Default: secrets)
  v2: false                         # bool     | Use legacy Helm v2 (Default: false)
  tillerNamespace: ""               # string   | Kubernetes namespace to run Tiller in when using Helm v2 (Default: "" = same a deployment namespace)
```
[Learn more about configuring deployments with Helm.](../configuration/deployments/helm-charts.mdx)

### `deployments[*].helm.componentChart`
```yaml
helm:
  componentChart: true              # bool     | Use Component chart
  values:                           # struct   | Options for deploying a component = Deployment/StatefulSet
    initContainers: ...             # struct[] | Init Containers of this Deployment/StatefulSet
    containers: ...                 # struct[] | Containers of this Deployment/StatefulSet
    labels: {}                      # map[string]string | Map of Kubernetes labels for labeling the pods of this component
    annotations: {}                 # map[string]string | Map of Kubernetes annotations for annotating the pods of this component
    volumes: ...                    # struct   | Component volumes
    service: ...                    # struct   | Component service
    serviceName: my-service         # string   | Service name for headless service (for StatefulSets)
    ingress: ...                    # struct   | Component ingress
    replicas: 1                     # int      | Number of replicas (Default: 1)
    autoScaling: ...                # struct   | AutoScaling configuration
    rollingUpdate: ...              # struct   | RollingUpdate configuration
    pullSecrets: ...                # string[] | Array of PullSecret names
    podManagementPolicy: OrderedReady # enum     | "OrderedReady" or "Parallel" (for StatefulSets)
    options: ...                    # struct   | Options for deploying this component with helm
```

[Learn more about configuring the component chart.](https://devspace.sh/component-chart/docs/introduction)

### `deployments[*].helm.chart`
```yaml
chart:                              # struct   | Chart to deploy
  name: my-chart                    # string   | Path to local chart on filesystem OR chart name for remote chart in helm chart repository
  version: v1.0.1                   # string   | Chart version
  repo: "https://my-repo.tld/"      # string   | Helm chart repository
  username: "my-username"           # string   | Username for Helm chart repository
  password: "my-password"           # string   | Password for Helm chart repository
```

### `deployments[*].kubectl`
```yaml
kubectl:                            # struct   | Options for deploying with "kubectl apply"
  manifests: []                     # string[] | Array containing glob patterns for the Kubernetes manifests to deploy using "kubectl apply" (e.g. kube or manifests/service.yaml)
  kustomize: false                  # bool     | Use kustomize when deploying manifests via "kubectl apply" (Default: false)
  replaceImageTags: true            # bool     | Enable automated tag replacement (Default: true)
  applyArgs: []                     # string[] | Array of args for the "kubectl apply" command during deployment
  createArgs: []                    # string[] | Array of args for the "kubectl create" command during deployment
  kustomizeArgs: []                 # string[] | Array of args for the "kustomize build" command during deployment
  deleteArgs: []                    # string[] | Array of args for the "kubectl delete" command when purging deployments
  cmdPath: ""                       # string   | Path to the kubectl binary (Default: "" = detect automatically)
```
[Learn more about configuring deployments with kubectl.](../configuration/deployments/kubernetes-manifests.mdx)


## `dev`

<FragmentConfigDev/>

[Learn more about configuring development mode.](../configuration/development/basics.mdx)

### `dev.ports`
```yaml
ports:                              # struct[] | Array of port forwarding settings for selected pods
- imageName: someImage              # string   | Name of an image defined in `images` to select pods with
  labelSelector: ...                # struct   | Key Value map of labels and values to select pods with
  namespace: ""                     # string   | Kubernetes namespace to select pods in
  forward:                          # struct[] | Array of ports to be forwarded
  - port: 8080                      # int      | Forward this port on your local computer
    remotePort: 3000                # int      | Forward traffic to this port exposed by the pod/container selected
    bindAddress: ""                 # string   | Address used for binding / use 0.0.0.0 to bind on all interfaces (Default: "localhost" = 127.0.0.1)
```
[Learn more about configuring port forwarding.](../configuration/development/port-forwarding.mdx)

### `dev.open`
```yaml
open:                               # struct[] | Array of auto-open settings
- url: "https://localhost:3000/"    # string   | URL to open after application has started
```
[Learn more about configuring auto-opening links.](../configuration/development/open-links.mdx)

### `dev.sync`
```yaml
sync:                               # struct[] | Array of file sync settings for selected pods
- imageName: someImage              # string   | Name of an image defined in `images` to select pods with
  labelSelector: ...                # struct   | Key Value map of labels and values to select pods with
  containerName: ""                 # string   | Container name to use after selecting a pod
  namespace: ""                     # string   | Kubernetes namespace to select pods in
  localSubPath: ./                  # string   | Relative path to a local folder that should be synchronized (Default: "./" = entire project)
  containerPath: /app               # string   | Path in the container that should be synchronized with localSubPath (Default is working directory of container ("."))
  excludePaths: []                  # string[] | Paths to exclude files/folders from sync in .gitignore syntax
  downloadExcludePaths: []          # string[] | Paths to exclude files/folders from download in .gitignore syntax
  uploadExcludePaths: []            # string[] | Paths to exclude files/folders from upload in .gitignore syntax
  initialSync: mirrorLocal          # enum     | Specifies the initialSync algorithm: mirrorLocal, mirrorRemote, preferLocal, preferRemote, preferNewest, keepAll (Default: mirrorLocal)
  waitInitialSync: false            # bool     | Wait until initial sync is completed before continuing (Default: false)
  bandwidthLimits:                  # struct   | Bandwidth limits for the synchronization algorithm
    download: 0                     # int64    | Max file download speed in kilobytes / second (e.g. 100 means 100 KB/s)
    upload: 0                       # int64    | Max file upload speed in kilobytes / second (e.g. 100 means 100 KB/s)
  onUpload:                         # struct   | After a file/folder has been uploaded to the container...
    restartContainer: true          # bool     | Restart container after uploading files (requires images.*.injectRestartHelper: true)
    execRemote:                     # struct   | ...execute the following command inside the container:
      command: chmod                # string   | Command to execute for files and folders
      args:                         # string[] | Argument list
      - +x                          # string   | Argument 1
      - {}                          # string   | Argument 2: {} will be replaced with path of the file/folder
      onFileChange:                 # struct   | Command to execute ONLY for files
        command: chmod              # string   | Command
        args:                       # string[] | Argument list
        - +x                        # string   | Argument 1
        - {}                        # string   | Argument 2: {} will be replaced with path of the file/folder
      onDirCreate:                  # struct   | Command to execute ONLY for newly created directories
        command: chmod              # string   | Command
        args:                       # string[] | Argument list
        - +x                        # string   | Argument 1
        - {}                        # string   | Argument 2: {} will be replaced with path of the file/folder
      onBatch:                      # struct   | Command to execute after sync has processed a full batch of files and folders
        command: recompile          # string   | Command
        args:                       # string[] | Argument list (NOTE: {} is NOT available for onBatch)
        - assets                    # string   | Arument 1
        - --minify                  # string   | Argument 2
  onDownload:                       # struct   | After a file/folder has been downloaded from the container to the local filesystem...
    execLocal:                      # struct   | ...execute the following command on the local machine:
      command: chmod                # string   | Command to execute for files and folders
      args:                         # string[] | Argument list
      - +x                          # string   | Argument 1
      - {}                          # string   | Argument 2: {} will be replaced with path of the file/folder
      onFileChange:                 # struct   | Command to execute ONLY for files
        command: chmod              # string   | Command
        args:                       # string[] | Argument list
        - +x                        # string   | Argument 1
        - {}                        # string   | Argument 2: {} will be replaced with path of the file/folder
      onDirCreate:                  # struct   | Command to execute ONLY for newly created directories
        command: chmod              # string   | Command
        args:                       # string[] | Argument list
        - +x                        # string   | Argument 1
        - {}                        # string   | Argument 2: {} will be replaced with path of the file/folder
```
[Learn more about confguring the file synchronization.](../configuration/development/file-synchronization.mdx)

### `dev.logs`
```yaml
logs:                               # struct   | Options for multi-container log streaming in development mode
  disabled: false                   # bool     | Disable log streaming in development mode (Default: false)
  showLast: 200                     # int      | Number of last log lines to show before starting stream (Default: 50)
  images: []                        # string[] | Array of image names referencing images defined in `images` for selecting containers for log streaming
```
[Learn more about configuring multi-container log streaming.](../configuration/development/log-streaming.mdx)

### `dev.autoReload`
```yaml
autoReload:                         # struct   | Options for auto-reloading (i.e. re-deploying deployments and re-building images)
  paths: []                         # string[] | Array containing glob patterns of files that are watched for auto-reloading (i.e. reload when a file matching any of the patterns changes)
  deployments: []                   # string[] | Array containing names of deployments to watch for auto-reloading (i.e. reload when kubectl manifests or files within the Helm chart change)
  images: []                        # string[] | Array containing names of images to watch for auto-reloading (i.e. reload when the Dockerfile changes)
```

### `dev.interactive`
```yaml
interactive:                        # struct   | Options for interactive mode
  defaultEnabled: false             # bool     | Start interactive mode instead of log streaming by default, even without -i / --interactive flag (Default: false)
  images:                           # struct[] | Array of image override configurations for interactive mode
  - name: default                   # string   | Name of the image to apply this override rule to (key in `images`)
    entrypoint: []                  # string[] | Array defining with the ENTRYPOINT that should be used instead of the ENTRYPOINT defined in the Dockerfile
    cmd: []                         # string[] | Array defining with the CMD that should be used instead of the CMD defined in the Dockerfile
  terminal:                         # struct   | Options for the terminal proxy
    imageName: someImage            # string   | Name of an image defined in `images` to select pods with
    labelSelector: ...              # struct   | Key Value map of labels and values to select pods with
    containerName: ""               # string   | Container name to use after selecting a pod
    namespace: ""                   # string   | Kubernetes namespace to select pods in
    command: []                     # string[] | Array defining the shell command to start the terminal with (Default: ["sh", "-c", "command -v bash >/dev/null 2>&1 && exec bash || exec sh"])
```
[Learn more about configuring interactive mode.](../configuration/development/interactive-mode.mdx)


## `dependencies`

<FragmentConfigDependencies/>

[Learn more about configuring dependencies.](../configuration/dependencies/basics.mdx)

:::warning
You **cannot** use `source.git` and `source.path` in combination. You **must** exactly use one of the two.
:::

## `hooks`

<FragmentConfigHooks/>


## `commands`

<FragmentConfigCommands/>

[Learn more about configuring custom commands.](../configuration/commands/basics.mdx)


## `vars`

<FragmentConfigVars/>

[Learn more about configuring config variables.](../configuration/variables/basics.mdx)


## `profiles`

<FragmentConfigProfiles/>

[Learn more about configuring profiles and patches.](../configuration/profiles/basics.mdx)
